wildpocketsfandomcom-20200213-history
Programming Manual Chap. 05
Event System Basics Wild Pockets has an "event system" whose primary purpose is to notify the program of keyboard keys, mouse clicks, and mouse movement. The event system works as follows: every event has a name, such as "keyPress-leftMouse". To respond to events, you must create an EventMap that connects event names to event handling functions. Here is a simple example: local eventmap = EventMap.new() eventmap:setEvent("keyPress-left", handleLeftArrow) eventmap:setEvent("keyPress-right", handleRightArrow) EventHandler.push(eventmap) function handleLeftArrow() print("You pressed the left arrow key.") end function handleRightArrow() print("You pressed the right arrow key.") end The EventMap is basically a table of event names and functions. The command EventHandler.push adds the EventMap to the "event stack." When an event occurs (such as the user pressing a mouse button), the system looks at all the EventMaps in the event stack, starting with the most-recently added EventMap. If the EventMap has an entry for the relevant event name, then the function is called, and event handling is done. If not, the next EventMap in the stack is checked until finally an EventMap responds to the event. Major Event Types Here is a list of all the major event categories: *'keyPress' events. The event name is the word "keyPress" concatenated to a dash and then the key-name. For example, the event name might be keyPress-left, keyPress-tab, or keyPress-a. These are sent whenever the user pushes a button on the keyboard or the mouse. These events are untranslated. For instance, on my US keyboard, the "1" key also has an exclamation point "!". If I press shift-1, the events I receive are "keyPress-shift" then "keyPress-1", not "keyPress-!". Mouse buttons also send keyPress events (keyPress-leftMouse, keyPress-rightMouse). *'keyRepeat' events. These are sent whenever the keyboard's autorepeat function triggers. You will only receive a keyRepeat event if you have previously received the corresponding keyPress event. *'keyRelease' events. These are sent whenever you let go of the button on the keyboard. You will only receive a keyRelease if you have previously received the corresponding keyPress event. *'keyDown' events. When a keyboard key is down, a keyDown event is sent every frame. This differs from keyRepeat in that keyRepeat events are only sent when the operating system autorepeat triggers, whereas keyDown events are sent every frame. *'characterPressed' events. These events are sent whenever the user has typed a character on the keyboard. If I press shift-1 on my US keyboard, the characterPressed event for exclamation point will be sent. Unlike keyPress events, the event name is just "characterPressed". The actual character is passed separately (see below). Event Arguments Event handling functions may receive additional arguments, depending on the event type. This table shows the arguments for each event type: *keyPress shiftFlag ctrlFlag *keyRepeat shiftFlag ctrlFlag *keyRelease shiftFlag ctrlFlag *keyDown *characterPressed characterAsciiCode The shiftFlag and ctrlFlag are attached to key-related events to indicate what state the keyboard shift and ctrl keys were in when the event was sent. Note that the keyDown event doesn't contain these values yet. You can get the same information by calling EventHandler.getKeyDown("shift") and the like. Here's some example code that utilizes these extra arguments: function onSceneStart() local evt = EventMap.new() EventMap:setEvent("keyPress-enter", handleEnterKey) EventHandler.push(evt) end function handleEnterKey(shiftFlag, ctrlFlag) print("Somebody pressed the Enter key.") print("Shift key down: ", shiftFlag) print("Control key down: ", ctrlFlag) end List of all Keyboard Key Names *leftMouse *rightMouse *middleMouse *backspace *tab *enter *shift *ctrl *pause *capsLock *esc *space *pageUp *pageDown *end *home *left *up *right *down *insert *delete *0 *1 *2 *3 *4 *5 *6 *7 *8 *9 *a *b *c *d *e *f *g *h *i *j *k *l *m *n *o *p *q *r *s *t *u *v *w *x *y *z *num+ *num- *f1 *f2 *f3 *f4 *f5 *f6 *f7 *f8 *f9 *f10 *f11 *f12 *numLock *scrollLock *; *= *, *- *. */ *` *[ *\ *] *' Other Keyboard and Mouse-Related Operations You can just ask whether or not a given key is pressed by calling EventHandler.keyIsDown(key). The argument to this function is a key-name as you might find in a keyPress event. It is possible to get the mouse position without using events by calling Mouse:getX, Mouse:getY, or Mouse:getXY (which returns two values). It is also possible to find out what object in the scene the mouse is pointing at by calling Mouse:getTopObject.